Endpoint Common Features

Some aspects of the Keyfactor API An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. request and response formats are consistent across all endpoints. This includes a small set of HTTP headers, HTTP statuses returned by the server for successful requests, and various error conditions. Common request headers are given in Table 138: Common Request Headers, common response headers (for successful requests and certain unsuccessful requests) are given in Table 139: Common Response Headers, and HTTP statuses are given in Table 140: HTTP Statuses.

By default, all Keyfactor API methods start with a base path, which corresponds to an application under IIS; this path is configurable at install time. The default base path is KeyfactorApi. The API component name and method name then comprise the parts of the URL, each separated by a forward slash. For example, /KeyfactorApi/Certificates/Import would be the URL format for the Import method of the Certificates component.

Table 138: Common Request Headers

Header Name	API Version	Header Value	Description
Content-Type	Both	application/json OR application/xml	POST methods use application/json. When application/xml is needed, it is specifically indicated on the endpoint page.
Accept	Both	application/json; charset=utf-8	Most methods returning complex values will use this content type.
Authorization	Both	Basic <base-64 DOMAIN\user:pass>	In most cases, Web API clients will use Basic authentication over SSL/TLS.
Host	Both	<Keyfactor Command server hostname>	Address of Keyfactor Command server. Automatically generated in most clients.
Content-Length	Both	Request length in bytes	Optional, but automatically generated by most clients.
X-Keyfactor-Requested-With	Both	XMLHttpRequest	This is mandatory to send in a request to the Keyfactor API on POSTs, PUTs, and DELETEs, and the value is case sensitive. This is for security.
X-Keyfactor-API-Version	Keyfactor API	1 or 2	Desired version of the endpoint. If not provided, this defaults to version 1.

Table 139: Common Response Headers

Header Name	Header Value	Description
Cache-Control	no-cache	API requests are generally not cacheable. Note that this is not respected by all client systems.
Pragma	no-cache	API requests are generally not cacheable. Note that this is not respected by all client systems.
Content-Length	<varies>	Length of the HTTP response.
Content-Type	application/json	Most calls return application/json, but occasionally text/plain or text/xml.
Expires	-1	Usually ignored.
Server	<varies>	Software version reported by IIS platform hosting Keyfactor Command.
X-Keyfactor-Product-Version	<varies>	Keyfactor Command platform version.
X-Total-Count	<varies>	Total number of elements returned.
X-AspNet-Version	<varies>	Version of ASP.NET supporting Keyfactor Command installation.
X-Powered-By	ASP.NET	Header added by underlying ASP.NET implementation.
Date	<varies>	Timestamp of the HTTP response.

Table 140: HTTP Statuses

Number/Name	Description
200 OK	Request successful; results in response body
204 No Content	Request successful; no content in response body
400 Bad Request	Malformed or invalid data; additional information may be available in the response body and/or Keyfactor Command server logs
401 Unauthorized	Invalid credentials (user unauthenticated)
403 Forbidden	Can often indicate that the credentials map to a user without permissions for this action in Keyfactor Command (user unauthorized)
404 Page not Found	Invalid request path
500 Internal Server Error	Keyfactor Command encountered an unexpected error attempting to handle the request. See response body and Keyfactor Command server logs for details.
502 Bad Gateway	Keyfactor Command attempted to contact a CA or other upstream server to process the request, but was unable to. See Keyfactor Command server logs for details.